home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / gcc / gcc261a.zoo / info / gcc.info-16 < prev    next >
Encoding:
GNU Info File  |  1994-10-31  |  47.6 KB  |  1,088 lines

  1. This is Info file gcc.info, produced by Makeinfo-1.54 from the input
  2. file gcc.texi.
  3.  
  4.    This file documents the use and the internals of the GNU compiler.
  5.  
  6.    Published by the Free Software Foundation 675 Massachusetts Avenue
  7. Cambridge, MA 02139 USA
  8.  
  9.    Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc.
  10.  
  11.    Permission is granted to make and distribute verbatim copies of this
  12. manual provided the copyright notice and this permission notice are
  13. preserved on all copies.
  14.  
  15.    Permission is granted to copy and distribute modified versions of
  16. this manual under the conditions for verbatim copying, provided also
  17. that the sections entitled "GNU General Public License" and "Protect
  18. Your Freedom--Fight `Look And Feel'" are included exactly as in the
  19. original, and provided that the entire resulting derived work is
  20. distributed under the terms of a permission notice identical to this
  21. one.
  22.  
  23.    Permission is granted to copy and distribute translations of this
  24. manual into another language, under the above conditions for modified
  25. versions, except that the sections entitled "GNU General Public
  26. License" and "Protect Your Freedom--Fight `Look And Feel'", and this
  27. permission notice, may be included in translations approved by the Free
  28. Software Foundation instead of in the original English.
  29.  
  30. File: gcc.info,  Node: Standard Names,  Next: Pattern Ordering,  Prev: Constraints,  Up: Machine Desc
  31.  
  32. Standard Pattern Names For Generation
  33. =====================================
  34.  
  35.    Here is a table of the instruction names that are meaningful in the
  36. RTL generation pass of the compiler.  Giving one of these names to an
  37. instruction pattern tells the RTL generation pass that it can use the
  38. pattern in to accomplish a certain task.
  39.  
  40. `movM'
  41.      Here M stands for a two-letter machine mode name, in lower case.
  42.      This instruction pattern moves data with that machine mode from
  43.      operand 1 to operand 0.  For example, `movsi' moves full-word data.
  44.  
  45.      If operand 0 is a `subreg' with mode M of a register whose own
  46.      mode is wider than M, the effect of this instruction is to store
  47.      the specified value in the part of the register that corresponds
  48.      to mode M.  The effect on the rest of the register is undefined.
  49.  
  50.      This class of patterns is special in several ways.  First of all,
  51.      each of these names *must* be defined, because there is no other
  52.      way to copy a datum from one place to another.
  53.  
  54.      Second, these patterns are not used solely in the RTL generation
  55.      pass.  Even the reload pass can generate move insns to copy values
  56.      from stack slots into temporary registers.  When it does so, one
  57.      of the operands is a hard register and the other is an operand
  58.      that can need to be reloaded into a register.
  59.  
  60.      Therefore, when given such a pair of operands, the pattern must
  61.      generate RTL which needs no reloading and needs no temporary
  62.      registers--no registers other than the operands.  For example, if
  63.      you support the pattern with a `define_expand', then in such a
  64.      case the `define_expand' mustn't call `force_reg' or any other such
  65.      function which might generate new pseudo registers.
  66.  
  67.      This requirement exists even for subword modes on a RISC machine
  68.      where fetching those modes from memory normally requires several
  69.      insns and some temporary registers.  Look in `spur.md' to see how
  70.      the requirement can be satisfied.
  71.  
  72.      During reload a memory reference with an invalid address may be
  73.      passed as an operand.  Such an address will be replaced with a
  74.      valid address later in the reload pass.  In this case, nothing may
  75.      be done with the address except to use it as it stands.  If it is
  76.      copied, it will not be replaced with a valid address.  No attempt
  77.      should be made to make such an address into a valid address and no
  78.      routine (such as `change_address') that will do so may be called.
  79.      Note that `general_operand' will fail when applied to such an
  80.      address.
  81.  
  82.      The global variable `reload_in_progress' (which must be explicitly
  83.      declared if required) can be used to determine whether such special
  84.      handling is required.
  85.  
  86.      The variety of operands that have reloads depends on the rest of
  87.      the machine description, but typically on a RISC machine these can
  88.      only be pseudo registers that did not get hard registers, while on
  89.      other machines explicit memory references will get optional
  90.      reloads.
  91.  
  92.      If a scratch register is required to move an object to or from
  93.      memory, it can be allocated using `gen_reg_rtx' prior to reload.
  94.      But this is impossible during and after reload.  If there are
  95.      cases needing scratch registers after reload, you must define
  96.      `SECONDARY_INPUT_RELOAD_CLASS' and perhaps also
  97.      `SECONDARY_OUTPUT_RELOAD_CLASS' to detect them, and provide
  98.      patterns `reload_inM' or `reload_outM' to handle them.  *Note
  99.      Register Classes::.
  100.  
  101.      The constraints on a `moveM' must permit moving any hard register
  102.      to any other hard register provided that `HARD_REGNO_MODE_OK'
  103.      permits mode M in both registers and `REGISTER_MOVE_COST' applied
  104.      to their classes returns a value of 2.
  105.  
  106.      It is obligatory to support floating point `moveM' instructions
  107.      into and out of any registers that can hold fixed point values,
  108.      because unions and structures (which have modes `SImode' or
  109.      `DImode') can be in those registers and they may have floating
  110.      point members.
  111.  
  112.      There may also be a need to support fixed point `moveM'
  113.      instructions in and out of floating point registers.
  114.      Unfortunately, I have forgotten why this was so, and I don't know
  115.      whether it is still true.  If `HARD_REGNO_MODE_OK' rejects fixed
  116.      point values in floating point registers, then the constraints of
  117.      the fixed point `moveM' instructions must be designed to avoid
  118.      ever trying to reload into a floating point register.
  119.  
  120. `reload_inM'
  121. `reload_outM'
  122.      Like `movM', but used when a scratch register is required to move
  123.      between operand 0 and operand 1.  Operand 2 describes the scratch
  124.      register.  See the discussion of the `SECONDARY_RELOAD_CLASS'
  125.      macro in *note Register Classes::..
  126.  
  127. `movstrictM'
  128.      Like `movM' except that if operand 0 is a `subreg' with mode M of
  129.      a register whose natural mode is wider, the `movstrictM'
  130.      instruction is guaranteed not to alter any of the register except
  131.      the part which belongs to mode M.
  132.  
  133. `load_multiple'
  134.      Load several consecutive memory locations into consecutive
  135.      registers.  Operand 0 is the first of the consecutive registers,
  136.      operand 1 is the first memory location, and operand 2 is a
  137.      constant: the number of consecutive registers.
  138.  
  139.      Define this only if the target machine really has such an
  140.      instruction; do not define this if the most efficient way of
  141.      loading consecutive registers from memory is to do them one at a
  142.      time.
  143.  
  144.      On some machines, there are restrictions as to which consecutive
  145.      registers can be stored into memory, such as particular starting or
  146.      ending register numbers or only a range of valid counts.  For those
  147.      machines, use a `define_expand' (*note Expander Definitions::.)
  148.      and make the pattern fail if the restrictions are not met.
  149.  
  150.      Write the generated insn as a `parallel' with elements being a
  151.      `set' of one register from the appropriate memory location (you may
  152.      also need `use' or `clobber' elements).  Use a `match_parallel'
  153.      (*note RTL Template::.) to recognize the insn.  See `a29k.md' and
  154.      `rs6000.md' for examples of the use of this insn pattern.
  155.  
  156. `store_multiple'
  157.      Similar to `load_multiple', but store several consecutive registers
  158.      into consecutive memory locations.  Operand 0 is the first of the
  159.      consecutive memory locations, operand 1 is the first register, and
  160.      operand 2 is a constant: the number of consecutive registers.
  161.  
  162. `addM3'
  163.      Add operand 2 and operand 1, storing the result in operand 0.  All
  164.      operands must have mode M.  This can be used even on two-address
  165.      machines, by means of constraints requiring operands 1 and 0 to be
  166.      the same location.
  167.  
  168. `subM3', `mulM3'
  169. `divM3', `udivM3', `modM3', `umodM3'
  170. `sminM3', `smaxM3', `uminM3', `umaxM3'
  171. `andM3', `iorM3', `xorM3'
  172.      Similar, for other arithmetic operations.
  173.  
  174. `mulhisi3'
  175.      Multiply operands 1 and 2, which have mode `HImode', and store a
  176.      `SImode' product in operand 0.
  177.  
  178. `mulqihi3', `mulsidi3'
  179.      Similar widening-multiplication instructions of other widths.
  180.  
  181. `umulqihi3', `umulhisi3', `umulsidi3'
  182.      Similar widening-multiplication instructions that do unsigned
  183.      multiplication.
  184.  
  185. `divmodM4'
  186.      Signed division that produces both a quotient and a remainder.
  187.      Operand 1 is divided by operand 2 to produce a quotient stored in
  188.      operand 0 and a remainder stored in operand 3.
  189.  
  190.      For machines with an instruction that produces both a quotient and
  191.      a remainder, provide a pattern for `divmodM4' but do not provide
  192.      patterns for `divM3' and `modM3'.  This allows optimization in the
  193.      relatively common case when both the quotient and remainder are
  194.      computed.
  195.  
  196.      If an instruction that just produces a quotient or just a remainder
  197.      exists and is more efficient than the instruction that produces
  198.      both, write the output routine of `divmodM4' to call
  199.      `find_reg_note' and look for a `REG_UNUSED' note on the quotient
  200.      or remainder and generate the appropriate instruction.
  201.  
  202. `udivmodM4'
  203.      Similar, but does unsigned division.
  204.  
  205. `ashlM3'
  206.      Arithmetic-shift operand 1 left by a number of bits specified by
  207.      operand 2, and store the result in operand 0.  Here M is the mode
  208.      of operand 0 and operand 1; operand 2's mode is specified by the
  209.      instruction pattern, and the compiler will convert the operand to
  210.      that mode before generating the instruction.
  211.  
  212. `ashrM3', `lshrM3', `rotlM3', `rotrM3'
  213.      Other shift and rotate instructions, analogous to the `ashlM3'
  214.      instructions.
  215.  
  216. `negM2'
  217.      Negate operand 1 and store the result in operand 0.
  218.  
  219. `absM2'
  220.      Store the absolute value of operand 1 into operand 0.
  221.  
  222. `sqrtM2'
  223.      Store the square root of operand 1 into operand 0.
  224.  
  225.      The `sqrt' built-in function of C always uses the mode which
  226.      corresponds to the C data type `double'.
  227.  
  228. `ffsM2'
  229.      Store into operand 0 one plus the index of the least significant
  230.      1-bit of operand 1.  If operand 1 is zero, store zero.  M is the
  231.      mode of operand 0; operand 1's mode is specified by the instruction
  232.      pattern, and the compiler will convert the operand to that mode
  233.      before generating the instruction.
  234.  
  235.      The `ffs' built-in function of C always uses the mode which
  236.      corresponds to the C data type `int'.
  237.  
  238. `one_cmplM2'
  239.      Store the bitwise-complement of operand 1 into operand 0.
  240.  
  241. `cmpM'
  242.      Compare operand 0 and operand 1, and set the condition codes.  The
  243.      RTL pattern should look like this:
  244.  
  245.           (set (cc0) (compare (match_operand:M 0 ...)
  246.                               (match_operand:M 1 ...)))
  247.  
  248. `tstM'
  249.      Compare operand 0 against zero, and set the condition codes.  The
  250.      RTL pattern should look like this:
  251.  
  252.           (set (cc0) (match_operand:M 0 ...))
  253.  
  254.      `tstM' patterns should not be defined for machines that do not use
  255.      `(cc0)'.  Doing so would confuse the optimizer since it would no
  256.      longer be clear which `set' operations were comparisons.  The
  257.      `cmpM' patterns should be used instead.
  258.  
  259. `movstrM'
  260.      Block move instruction.  The addresses of the destination and
  261.      source strings are the first two operands, and both are in mode
  262.      `Pmode'.  The number of bytes to move is the third operand, in
  263.      mode M.
  264.  
  265.      The fourth operand is the known shared alignment of the source and
  266.      destination, in the form of a `const_int' rtx.  Thus, if the
  267.      compiler knows that both source and destination are word-aligned,
  268.      it may provide the value 4 for this operand.
  269.  
  270.      These patterns need not give special consideration to the
  271.      possibility that the source and destination strings might overlap.
  272.  
  273. `cmpstrM'
  274.      Block compare instruction, with five operands.  Operand 0 is the
  275.      output; it has mode M.  The remaining four operands are like the
  276.      operands of `movstrM'.  The two memory blocks specified are
  277.      compared byte by byte in lexicographic order.  The effect of the
  278.      instruction is to store a value in operand 0 whose sign indicates
  279.      the result of the comparison.
  280.  
  281.      Compute the length of a string, with three operands.  Operand 0 is
  282.      the result (of mode M), operand 1 is a `mem' referring to the
  283.      first character of the string, operand 2 is the character to
  284.      search for (normally zero), and operand 3 is a constant describing
  285.      the known alignment of the beginning of the string.
  286.  
  287. `floatMN2'
  288.      Convert signed integer operand 1 (valid for fixed point mode M) to
  289.      floating point mode N and store in operand 0 (which has mode N).
  290.  
  291. `floatunsMN2'
  292.      Convert unsigned integer operand 1 (valid for fixed point mode M)
  293.      to floating point mode N and store in operand 0 (which has mode N).
  294.  
  295. `fixMN2'
  296.      Convert operand 1 (valid for floating point mode M) to fixed point
  297.      mode N as a signed number and store in operand 0 (which has mode
  298.      N).  This instruction's result is defined only when the value of
  299.      operand 1 is an integer.
  300.  
  301. `fixunsMN2'
  302.      Convert operand 1 (valid for floating point mode M) to fixed point
  303.      mode N as an unsigned number and store in operand 0 (which has
  304.      mode N).  This instruction's result is defined only when the value
  305.      of operand 1 is an integer.
  306.  
  307. `ftruncM2'
  308.      Convert operand 1 (valid for floating point mode M) to an integer
  309.      value, still represented in floating point mode M, and store it in
  310.      operand 0 (valid for floating point mode M).
  311.  
  312. `fix_truncMN2'
  313.      Like `fixMN2' but works for any floating point value of mode M by
  314.      converting the value to an integer.
  315.  
  316. `fixuns_truncMN2'
  317.      Like `fixunsMN2' but works for any floating point value of mode M
  318.      by converting the value to an integer.
  319.  
  320. `truncMN'
  321.      Truncate operand 1 (valid for mode M) to mode N and store in
  322.      operand 0 (which has mode N).  Both modes must be fixed point or
  323.      both floating point.
  324.  
  325. `extendMN'
  326.      Sign-extend operand 1 (valid for mode M) to mode N and store in
  327.      operand 0 (which has mode N).  Both modes must be fixed point or
  328.      both floating point.
  329.  
  330. `zero_extendMN'
  331.      Zero-extend operand 1 (valid for mode M) to mode N and store in
  332.      operand 0 (which has mode N).  Both modes must be fixed point.
  333.  
  334. `extv'
  335.      Extract a bit field from operand 1 (a register or memory operand),
  336.      where operand 2 specifies the width in bits and operand 3 the
  337.      starting bit, and store it in operand 0.  Operand 0 must have mode
  338.      `word_mode'.  Operand 1 may have mode `byte_mode' or `word_mode';
  339.      often `word_mode' is allowed only for registers.  Operands 2 and 3
  340.      must be valid for `word_mode'.
  341.  
  342.      The RTL generation pass generates this instruction only with
  343.      constants for operands 2 and 3.
  344.  
  345.      The bit-field value is sign-extended to a full word integer before
  346.      it is stored in operand 0.
  347.  
  348. `extzv'
  349.      Like `extv' except that the bit-field value is zero-extended.
  350.  
  351. `insv'
  352.      Store operand 3 (which must be valid for `word_mode') into a bit
  353.      field in operand 0, where operand 1 specifies the width in bits and
  354.      operand 2 the starting bit.  Operand 0 may have mode `byte_mode' or
  355.      `word_mode'; often `word_mode' is allowed only for registers.
  356.      Operands 1 and 2 must be valid for `word_mode'.
  357.  
  358.      The RTL generation pass generates this instruction only with
  359.      constants for operands 1 and 2.
  360.  
  361. `sCOND'
  362.      Store zero or nonzero in the operand according to the condition
  363.      codes.  Value stored is nonzero iff the condition COND is true.
  364.      cOND is the name of a comparison operation expression code, such
  365.      as `eq', `lt' or `leu'.
  366.  
  367.      You specify the mode that the operand must have when you write the
  368.      `match_operand' expression.  The compiler automatically sees which
  369.      mode you have used and supplies an operand of that mode.
  370.  
  371.      The value stored for a true condition must have 1 as its low bit,
  372.      or else must be negative.  Otherwise the instruction is not
  373.      suitable and you should omit it from the machine description.  You
  374.      describe to the compiler exactly which value is stored by defining
  375.      the macro `STORE_FLAG_VALUE' (*note Misc::.).  If a description
  376.      cannot be found that can be used for all the `sCOND' patterns, you
  377.      should omit those operations from the machine description.
  378.  
  379.      These operations may fail, but should do so only in relatively
  380.      uncommon cases; if they would fail for common cases involving
  381.      integer comparisons, it is best to omit these patterns.
  382.  
  383.      If these operations are omitted, the compiler will usually
  384.      generate code that copies the constant one to the target and
  385.      branches around an assignment of zero to the target.  If this code
  386.      is more efficient than the potential instructions used for the
  387.      `sCOND' pattern followed by those required to convert the result
  388.      into a 1 or a zero in `SImode', you should omit the `sCOND'
  389.      operations from the machine description.
  390.  
  391. `bCOND'
  392.      Conditional branch instruction.  Operand 0 is a `label_ref' that
  393.      refers to the label to jump to.  Jump if the condition codes meet
  394.      condition COND.
  395.  
  396.      Some machines do not follow the model assumed here where a
  397.      comparison instruction is followed by a conditional branch
  398.      instruction.  In that case, the `cmpM' (and `tstM') patterns should
  399.      simply store the operands away and generate all the required insns
  400.      in a `define_expand' (*note Expander Definitions::.) for the
  401.      conditional branch operations.  All calls to expand `bCOND'
  402.      patterns are immediately preceded by calls to expand either a
  403.      `cmpM' pattern or a `tstM' pattern.
  404.  
  405.      Machines that use a pseudo register for the condition code value,
  406.      or where the mode used for the comparison depends on the condition
  407.      being tested, should also use the above mechanism.  *Note Jump
  408.      Patterns::
  409.  
  410.      The above discussion also applies to `sCOND' patterns.
  411.  
  412. `call'
  413.      Subroutine call instruction returning no value.  Operand 0 is the
  414.      function to call; operand 1 is the number of bytes of arguments
  415.      pushed (in mode `SImode', except it is normally a `const_int');
  416.      operand 2 is the number of registers used as operands.
  417.  
  418.      On most machines, operand 2 is not actually stored into the RTL
  419.      pattern.  It is supplied for the sake of some RISC machines which
  420.      need to put this information into the assembler code; they can put
  421.      it in the RTL instead of operand 1.
  422.  
  423.      Operand 0 should be a `mem' RTX whose address is the address of the
  424.      function.  Note, however, that this address can be a `symbol_ref'
  425.      expression even if it would not be a legitimate memory address on
  426.      the target machine.  If it is also not a valid argument for a call
  427.      instruction, the pattern for this operation should be a
  428.      `define_expand' (*note Expander Definitions::.) that places the
  429.      address into a register and uses that register in the call
  430.      instruction.
  431.  
  432. `call_value'
  433.      Subroutine call instruction returning a value.  Operand 0 is the
  434.      hard register in which the value is returned.  There are three more
  435.      operands, the same as the three operands of the `call' instruction
  436.      (but with numbers increased by one).
  437.  
  438.      Subroutines that return `BLKmode' objects use the `call' insn.
  439.  
  440. `call_pop', `call_value_pop'
  441.      Similar to `call' and `call_value', except used if defined and if
  442.      `RETURN_POPS_ARGS' is non-zero.  They should emit a `parallel'
  443.      that contains both the function call and a `set' to indicate the
  444.      adjustment made to the frame pointer.
  445.  
  446.      For machines where `RETURN_POPS_ARGS' can be non-zero, the use of
  447.      these patterns increases the number of functions for which the
  448.      frame pointer can be eliminated, if desired.
  449.  
  450. `untyped_call'
  451.      Subroutine call instruction returning a value of any type.
  452.      Operand 0 is the function to call; operand 1 is a memory location
  453.      where the result of calling the function is to be stored; operand
  454.      2 is a `parallel' expression where each element is a `set'
  455.      expression that indicates the saving of a function return value
  456.      into the result block.
  457.  
  458.      This instruction pattern should be defined to support
  459.      `__builtin_apply' on machines where special instructions are needed
  460.      to call a subroutine with arbitrary arguments or to save the value
  461.      returned.  This instruction pattern is required on machines that
  462.      have multiple registers that can hold a return value (i.e.
  463.      `FUNCTION_VALUE_REGNO_P' is true for more than one register).
  464.  
  465. `return'
  466.      Subroutine return instruction.  This instruction pattern name
  467.      should be defined only if a single instruction can do all the work
  468.      of returning from a function.
  469.  
  470.      Like the `movM' patterns, this pattern is also used after the RTL
  471.      generation phase.  In this case it is to support machines where
  472.      multiple instructions are usually needed to return from a
  473.      function, but some class of functions only requires one
  474.      instruction to implement a return.  Normally, the applicable
  475.      functions are those which do not need to save any registers or
  476.      allocate stack space.
  477.  
  478.      For such machines, the condition specified in this pattern should
  479.      only be true when `reload_completed' is non-zero and the function's
  480.      epilogue would only be a single instruction.  For machines with
  481.      register windows, the routine `leaf_function_p' may be used to
  482.      determine if a register window push is required.
  483.  
  484.      Machines that have conditional return instructions should define
  485.      patterns such as
  486.  
  487.           (define_insn ""
  488.             [(set (pc)
  489.                   (if_then_else (match_operator
  490.                                    0 "comparison_operator"
  491.                                    [(cc0) (const_int 0)])
  492.                                 (return)
  493.                                 (pc)))]
  494.             "CONDITION"
  495.             "...")
  496.  
  497.      where CONDITION would normally be the same condition specified on
  498.      the named `return' pattern.
  499.  
  500. `untyped_return'
  501.      Untyped subroutine return instruction.  This instruction pattern
  502.      should be defined to support `__builtin_return' on machines where
  503.      special instructions are needed to return a value of any type.
  504.  
  505.      Operand 0 is a memory location where the result of calling a
  506.      function with `__builtin_apply' is stored; operand 1 is a
  507.      `parallel' expression where each element is a `set' expression
  508.      that indicates the restoring of a function return value from the
  509.      result block.
  510.  
  511. `nop'
  512.      No-op instruction.  This instruction pattern name should always be
  513.      defined to output a no-op in assembler code.  `(const_int 0)' will
  514.      do as an RTL pattern.
  515.  
  516. `indirect_jump'
  517.      An instruction to jump to an address which is operand zero.  This
  518.      pattern name is mandatory on all machines.
  519.  
  520. `casesi'
  521.      Instruction to jump through a dispatch table, including bounds
  522.      checking.  This instruction takes five operands:
  523.  
  524.        1. The index to dispatch on, which has mode `SImode'.
  525.  
  526.        2. The lower bound for indices in the table, an integer constant.
  527.  
  528.        3. The total range of indices in the table--the largest index
  529.           minus the smallest one (both inclusive).
  530.  
  531.        4. A label that precedes the table itself.
  532.  
  533.        5. A label to jump to if the index has a value outside the
  534.           bounds.  (If the machine-description macro
  535.           `CASE_DROPS_THROUGH' is defined, then an out-of-bounds index
  536.           drops through to the code following the jump table instead of
  537.           jumping to this label.  In that case, this label is not
  538.           actually used by the `casesi' instruction, but it is always
  539.           provided as an operand.)
  540.  
  541.      The table is a `addr_vec' or `addr_diff_vec' inside of a
  542.      `jump_insn'.  The number of elements in the table is one plus the
  543.      difference between the upper bound and the lower bound.
  544.  
  545. `tablejump'
  546.      Instruction to jump to a variable address.  This is a low-level
  547.      capability which can be used to implement a dispatch table when
  548.      there is no `casesi' pattern.
  549.  
  550.      This pattern requires two operands: the address or offset, and a
  551.      label which should immediately precede the jump table.  If the
  552.      macro `CASE_VECTOR_PC_RELATIVE' is defined then the first operand
  553.      is an offset which counts from the address of the table;
  554.      otherwise, it is an absolute address to jump to.  In either case,
  555.      the first operand has mode `Pmode'.
  556.  
  557.      The `tablejump' insn is always the last insn before the jump table
  558.      it uses.  Its assembler code normally has no need to use the
  559.      second operand, but you should incorporate it in the RTL pattern so
  560.      that the jump optimizer will not delete the table as unreachable
  561.      code.
  562.  
  563. `save_stack_block'
  564. `save_stack_function'
  565. `save_stack_nonlocal'
  566. `restore_stack_block'
  567. `restore_stack_function'
  568. `restore_stack_nonlocal'
  569.      Most machines save and restore the stack pointer by copying it to
  570.      or from an object of mode `Pmode'.  Do not define these patterns on
  571.      such machines.
  572.  
  573.      Some machines require special handling for stack pointer saves and
  574.      restores.  On those machines, define the patterns corresponding to
  575.      the non-standard cases by using a `define_expand' (*note Expander
  576.      Definitions::.) that produces the required insns.  The three types
  577.      of saves and restores are:
  578.  
  579.        1. `save_stack_block' saves the stack pointer at the start of a
  580.           block that allocates a variable-sized object, and
  581.           `restore_stack_block' restores the stack pointer when the
  582.           block is exited.
  583.  
  584.        2. `save_stack_function' and `restore_stack_function' do a
  585.           similar job for the outermost block of a function and are
  586.           used when the function allocates variable-sized objects or
  587.           calls `alloca'.  Only the epilogue uses the restored stack
  588.           pointer, allowing a simpler save or restore sequence on some
  589.           machines.
  590.  
  591.        3. `save_stack_nonlocal' is used in functions that contain labels
  592.           branched to by nested functions.  It saves the stack pointer
  593.           in such a way that the inner function can use
  594.           `restore_stack_nonlocal' to restore the stack pointer.  The
  595.           compiler generates code to restore the frame and argument
  596.           pointer registers, but some machines require saving and
  597.           restoring additional data such as register window information
  598.           or stack backchains.  Place insns in these patterns to save
  599.           and restore any such required data.
  600.  
  601.      When saving the stack pointer, operand 0 is the save area and
  602.      operand 1 is the stack pointer.  The mode used to allocate the
  603.      save area is the mode of operand 0.  You must specify an integral
  604.      mode, or `VOIDmode' if no save area is needed for a particular
  605.      type of save (either because no save is needed or because a
  606.      machine-specific save area can be used).  Operand 0 is the stack
  607.      pointer and operand 1 is the save area for restore operations.  If
  608.      `save_stack_block' is defined, operand 0 must not be `VOIDmode'
  609.      since these saves can be arbitrarily nested.
  610.  
  611.      A save area is a `mem' that is at a constant offset from
  612.      `virtual_stack_vars_rtx' when the stack pointer is saved for use by
  613.      nonlocal gotos and a `reg' in the other two cases.
  614.  
  615. `allocate_stack'
  616.      Subtract (or add if `STACK_GROWS_DOWNWARD' is undefined) operand 0
  617.      from the stack pointer to create space for dynamically allocated
  618.      data.
  619.  
  620.      Do not define this pattern if all that must be done is the
  621.      subtraction.  Some machines require other operations such as stack
  622.      probes or maintaining the back chain.  Define this pattern to emit
  623.      those operations in addition to updating the stack pointer.
  624.  
  625. File: gcc.info,  Node: Pattern Ordering,  Next: Dependent Patterns,  Prev: Standard Names,  Up: Machine Desc
  626.  
  627. When the Order of Patterns Matters
  628. ==================================
  629.  
  630.    Sometimes an insn can match more than one instruction pattern.  Then
  631. the pattern that appears first in the machine description is the one
  632. used.  Therefore, more specific patterns (patterns that will match
  633. fewer things) and faster instructions (those that will produce better
  634. code when they do match) should usually go first in the description.
  635.  
  636.    In some cases the effect of ordering the patterns can be used to hide
  637. a pattern when it is not valid.  For example, the 68000 has an
  638. instruction for converting a fullword to floating point and another for
  639. converting a byte to floating point.  An instruction converting an
  640. integer to floating point could match either one.  We put the pattern
  641. to convert the fullword first to make sure that one will be used rather
  642. than the other.  (Otherwise a large integer might be generated as a
  643. single-byte immediate quantity, which would not work.) Instead of using
  644. this pattern ordering it would be possible to make the pattern for
  645. convert-a-byte smart enough to deal properly with any constant value.
  646.  
  647. File: gcc.info,  Node: Dependent Patterns,  Next: Jump Patterns,  Prev: Pattern Ordering,  Up: Machine Desc
  648.  
  649. Interdependence of Patterns
  650. ===========================
  651.  
  652.    Every machine description must have a named pattern for each of the
  653. conditional branch names `bCOND'.  The recognition template must always
  654. have the form
  655.  
  656.      (set (pc)
  657.           (if_then_else (COND (cc0) (const_int 0))
  658.                         (label_ref (match_operand 0 "" ""))
  659.                         (pc)))
  660.  
  661. In addition, every machine description must have an anonymous pattern
  662. for each of the possible reverse-conditional branches.  Their templates
  663. look like
  664.  
  665.      (set (pc)
  666.           (if_then_else (COND (cc0) (const_int 0))
  667.                         (pc)
  668.                         (label_ref (match_operand 0 "" ""))))
  669.  
  670. They are necessary because jump optimization can turn direct-conditional
  671. branches into reverse-conditional branches.
  672.  
  673.    It is often convenient to use the `match_operator' construct to
  674. reduce the number of patterns that must be specified for branches.  For
  675. example,
  676.  
  677.      (define_insn ""
  678.        [(set (pc)
  679.              (if_then_else (match_operator 0 "comparison_operator"
  680.                                            [(cc0) (const_int 0)])
  681.                            (pc)
  682.                            (label_ref (match_operand 1 "" ""))))]
  683.        "CONDITION"
  684.        "...")
  685.  
  686.    In some cases machines support instructions identical except for the
  687. machine mode of one or more operands.  For example, there may be
  688. "sign-extend halfword" and "sign-extend byte" instructions whose
  689. patterns are
  690.  
  691.      (set (match_operand:SI 0 ...)
  692.           (extend:SI (match_operand:HI 1 ...)))
  693.      
  694.      (set (match_operand:SI 0 ...)
  695.           (extend:SI (match_operand:QI 1 ...)))
  696.  
  697. Constant integers do not specify a machine mode, so an instruction to
  698. extend a constant value could match either pattern.  The pattern it
  699. actually will match is the one that appears first in the file.  For
  700. correct results, this must be the one for the widest possible mode
  701. (`HImode', here).  If the pattern matches the `QImode' instruction, the
  702. results will be incorrect if the constant value does not actually fit
  703. that mode.
  704.  
  705.    Such instructions to extend constants are rarely generated because
  706. they are optimized away, but they do occasionally happen in nonoptimized
  707. compilations.
  708.  
  709.    If a constraint in a pattern allows a constant, the reload pass may
  710. replace a register with a constant permitted by the constraint in some
  711. cases.  Similarly for memory references.  You must ensure that the
  712. predicate permits all objects allowed by the constraints to prevent the
  713. compiler from crashing.
  714.  
  715.    Because of this substitution, you should not provide separate
  716. patterns for increment and decrement instructions.  Instead, they
  717. should be generated from the same pattern that supports
  718. register-register add insns by examining the operands and generating
  719. the appropriate machine instruction.
  720.  
  721. File: gcc.info,  Node: Jump Patterns,  Next: Insn Canonicalizations,  Prev: Dependent Patterns,  Up: Machine Desc
  722.  
  723. Defining Jump Instruction Patterns
  724. ==================================
  725.  
  726.    For most machines, GNU CC assumes that the machine has a condition
  727. code.  A comparison insn sets the condition code, recording the results
  728. of both signed and unsigned comparison of the given operands.  A
  729. separate branch insn tests the condition code and branches or not
  730. according its value.  The branch insns come in distinct signed and
  731. unsigned flavors.  Many common machines, such as the Vax, the 68000 and
  732. the 32000, work this way.
  733.  
  734.    Some machines have distinct signed and unsigned compare
  735. instructions, and only one set of conditional branch instructions.  The
  736. easiest way to handle these machines is to treat them just like the
  737. others until the final stage where assembly code is written.  At this
  738. time, when outputting code for the compare instruction, peek ahead at
  739. the following branch using `next_cc0_user (insn)'.  (The variable
  740. `insn' refers to the insn being output, in the output-writing code in
  741. an instruction pattern.)  If the RTL says that is an unsigned branch,
  742. output an unsigned compare; otherwise output a signed compare.  When
  743. the branch itself is output, you can treat signed and unsigned branches
  744. identically.
  745.  
  746.    The reason you can do this is that GNU CC always generates a pair of
  747. consecutive RTL insns, possibly separated by `note' insns, one to set
  748. the condition code and one to test it, and keeps the pair inviolate
  749. until the end.
  750.  
  751.    To go with this technique, you must define the machine-description
  752. macro `NOTICE_UPDATE_CC' to do `CC_STATUS_INIT'; in other words, no
  753. compare instruction is superfluous.
  754.  
  755.    Some machines have compare-and-branch instructions and no condition
  756. code.  A similar technique works for them.  When it is time to "output"
  757. a compare instruction, record its operands in two static variables.
  758. When outputting the branch-on-condition-code instruction that follows,
  759. actually output a compare-and-branch instruction that uses the
  760. remembered operands.
  761.  
  762.    It also works to define patterns for compare-and-branch instructions.
  763. In optimizing compilation, the pair of compare and branch instructions
  764. will be combined according to these patterns.  But this does not happen
  765. if optimization is not requested.  So you must use one of the solutions
  766. above in addition to any special patterns you define.
  767.  
  768.    In many RISC machines, most instructions do not affect the condition
  769. code and there may not even be a separate condition code register.  On
  770. these machines, the restriction that the definition and use of the
  771. condition code be adjacent insns is not necessary and can prevent
  772. important optimizations.  For example, on the IBM RS/6000, there is a
  773. delay for taken branches unless the condition code register is set three
  774. instructions earlier than the conditional branch.  The instruction
  775. scheduler cannot perform this optimization if it is not permitted to
  776. separate the definition and use of the condition code register.
  777.  
  778.    On these machines, do not use `(cc0)', but instead use a register to
  779. represent the condition code.  If there is a specific condition code
  780. register in the machine, use a hard register.  If the condition code or
  781. comparison result can be placed in any general register, or if there are
  782. multiple condition registers, use a pseudo register.
  783.  
  784.    On some machines, the type of branch instruction generated may
  785. depend on the way the condition code was produced; for example, on the
  786. 68k and Sparc, setting the condition code directly from an add or
  787. subtract instruction does not clear the overflow bit the way that a test
  788. instruction does, so a different branch instruction must be used for
  789. some conditional branches.  For machines that use `(cc0)', the set and
  790. use of the condition code must be adjacent (separated only by `note'
  791. insns) allowing flags in `cc_status' to be used.  (*Note Condition
  792. Code::.)  Also, the comparison and branch insns can be located from
  793. each other by using the functions `prev_cc0_setter' and `next_cc0_user'.
  794.  
  795.    However, this is not true on machines that do not use `(cc0)'.  On
  796. those machines, no assumptions can be made about the adjacency of the
  797. compare and branch insns and the above methods cannot be used.  Instead,
  798. we use the machine mode of the condition code register to record
  799. different formats of the condition code register.
  800.  
  801.    Registers used to store the condition code value should have a mode
  802. that is in class `MODE_CC'.  Normally, it will be `CCmode'.  If
  803. additional modes are required (as for the add example mentioned above in
  804. the Sparc), define the macro `EXTRA_CC_MODES' to list the additional
  805. modes required (*note Condition Code::.).  Also define `EXTRA_CC_NAMES'
  806. to list the names of those modes and `SELECT_CC_MODE' to choose a mode
  807. given an operand of a compare.
  808.  
  809.    If it is known during RTL generation that a different mode will be
  810. required (for example, if the machine has separate compare instructions
  811. for signed and unsigned quantities, like most IBM processors), they can
  812. be specified at that time.
  813.  
  814.    If the cases that require different modes would be made by
  815. instruction combination, the macro `SELECT_CC_MODE' determines which
  816. machine mode should be used for the comparison result.  The patterns
  817. should be written using that mode.  To support the case of the add on
  818. the Sparc discussed above, we have the pattern
  819.  
  820.      (define_insn ""
  821.        [(set (reg:CC_NOOV 0)
  822.              (compare:CC_NOOV
  823.                (plus:SI (match_operand:SI 0 "register_operand" "%r")
  824.                         (match_operand:SI 1 "arith_operand" "rI"))
  825.                (const_int 0)))]
  826.        ""
  827.        "...")
  828.  
  829.    The `SELECT_CC_MODE' macro on the Sparc returns `CC_NOOVmode' for
  830. comparisons whose argument is a `plus'.
  831.  
  832. File: gcc.info,  Node: Insn Canonicalizations,  Next: Peephole Definitions,  Prev: Jump Patterns,  Up: Machine Desc
  833.  
  834. Canonicalization of Instructions
  835. ================================
  836.  
  837.    There are often cases where multiple RTL expressions could represent
  838. an operation performed by a single machine instruction.  This situation
  839. is most commonly encountered with logical, branch, and
  840. multiply-accumulate instructions.  In such cases, the compiler attempts
  841. to convert these multiple RTL expressions into a single canonical form
  842. to reduce the number of insn patterns required.
  843.  
  844.    In addition to algebraic simplifications, following canonicalizations
  845. are performed:
  846.  
  847.    * For commutative and comparison operators, a constant is always
  848.      made the second operand.  If a machine only supports a constant as
  849.      the second operand, only patterns that match a constant in the
  850.      second operand need be supplied.
  851.  
  852.      For these operators, if only one operand is a `neg', `not',
  853.      `mult', `plus', or `minus' expression, it will be the first
  854.      operand.
  855.  
  856.    * For the `compare' operator, a constant is always the second operand
  857.      on machines where `cc0' is used (*note Jump Patterns::.).  On other
  858.      machines, there are rare cases where the compiler might want to
  859.      construct a `compare' with a constant as the first operand.
  860.      However, these cases are not common enough for it to be worthwhile
  861.      to provide a pattern matching a constant as the first operand
  862.      unless the machine actually has such an instruction.
  863.  
  864.      An operand of `neg', `not', `mult', `plus', or `minus' is made the
  865.      first operand under the same conditions as above.
  866.  
  867.    * `(minus X (const_int N))' is converted to `(plus X (const_int
  868.      -N))'.
  869.  
  870.    * Within address computations (i.e., inside `mem'), a left shift is
  871.      converted into the appropriate multiplication by a power of two.
  872.  
  873.      De`Morgan's Law is used to move bitwise negation inside a bitwise
  874.      logical-and or logical-or operation.  If this results in only one
  875.      operand being a `not' expression, it will be the first one.
  876.  
  877.      A machine that has an instruction that performs a bitwise
  878.      logical-and of one operand with the bitwise negation of the other
  879.      should specify the pattern for that instruction as
  880.  
  881.           (define_insn ""
  882.             [(set (match_operand:M 0 ...)
  883.                   (and:M (not:M (match_operand:M 1 ...))
  884.                                (match_operand:M 2 ...)))]
  885.             "..."
  886.             "...")
  887.  
  888.      Similarly, a pattern for a "NAND" instruction should be written
  889.  
  890.           (define_insn ""
  891.             [(set (match_operand:M 0 ...)
  892.                   (ior:M (not:M (match_operand:M 1 ...))
  893.                                (not:M (match_operand:M 2 ...))))]
  894.             "..."
  895.             "...")
  896.  
  897.      In both cases, it is not necessary to include patterns for the many
  898.      logically equivalent RTL expressions.
  899.  
  900.    * The only possible RTL expressions involving both bitwise
  901.      exclusive-or and bitwise negation are `(xor:M X Y)' and `(not:M
  902.      (xor:M X Y))'.
  903.  
  904.    * The sum of three items, one of which is a constant, will only
  905.      appear in the form
  906.  
  907.           (plus:M (plus:M X Y) CONSTANT)
  908.  
  909.    * On machines that do not use `cc0', `(compare X (const_int 0))'
  910.      will be converted to X.
  911.  
  912.    * Equality comparisons of a group of bits (usually a single bit)
  913.      with zero will be written using `zero_extract' rather than the
  914.      equivalent `and' or `sign_extract' operations.
  915.  
  916. File: gcc.info,  Node: Peephole Definitions,  Next: Expander Definitions,  Prev: Insn Canonicalizations,  Up: Machine Desc
  917.  
  918. Machine-Specific Peephole Optimizers
  919. ====================================
  920.  
  921.    In addition to instruction patterns the `md' file may contain
  922. definitions of machine-specific peephole optimizations.
  923.  
  924.    The combiner does not notice certain peephole optimizations when the
  925. data flow in the program does not suggest that it should try them.  For
  926. example, sometimes two consecutive insns related in purpose can be
  927. combined even though the second one does not appear to use a register
  928. computed in the first one.  A machine-specific peephole optimizer can
  929. detect such opportunities.
  930.  
  931.    A definition looks like this:
  932.  
  933.      (define_peephole
  934.        [INSN-PATTERN-1
  935.         INSN-PATTERN-2
  936.         ...]
  937.        "CONDITION"
  938.        "TEMPLATE"
  939.        "OPTIONAL INSN-ATTRIBUTES")
  940.  
  941. The last string operand may be omitted if you are not using any
  942. machine-specific information in this machine description.  If present,
  943. it must obey the same rules as in a `define_insn'.
  944.  
  945.    In this skeleton, INSN-PATTERN-1 and so on are patterns to match
  946. consecutive insns.  The optimization applies to a sequence of insns when
  947. INSN-PATTERN-1 matches the first one, INSN-PATTERN-2 matches the next,
  948. and so on.
  949.  
  950.    Each of the insns matched by a peephole must also match a
  951. `define_insn'.  Peepholes are checked only at the last stage just
  952. before code generation, and only optionally.  Therefore, any insn which
  953. would match a peephole but no `define_insn' will cause a crash in code
  954. generation in an unoptimized compilation, or at various optimization
  955. stages.
  956.  
  957.    The operands of the insns are matched with `match_operands',
  958. `match_operator', and `match_dup', as usual.  What is not usual is that
  959. the operand numbers apply to all the insn patterns in the definition.
  960. So, you can check for identical operands in two insns by using
  961. `match_operand' in one insn and `match_dup' in the other.
  962.  
  963.    The operand constraints used in `match_operand' patterns do not have
  964. any direct effect on the applicability of the peephole, but they will
  965. be validated afterward, so make sure your constraints are general enough
  966. to apply whenever the peephole matches.  If the peephole matches but
  967. the constraints are not satisfied, the compiler will crash.
  968.  
  969.    It is safe to omit constraints in all the operands of the peephole;
  970. or you can write constraints which serve as a double-check on the
  971. criteria previously tested.
  972.  
  973.    Once a sequence of insns matches the patterns, the CONDITION is
  974. checked.  This is a C expression which makes the final decision whether
  975. to perform the optimization (we do so if the expression is nonzero).  If
  976. CONDITION is omitted (in other words, the string is empty) then the
  977. optimization is applied to every sequence of insns that matches the
  978. patterns.
  979.  
  980.    The defined peephole optimizations are applied after register
  981. allocation is complete.  Therefore, the peephole definition can check
  982. which operands have ended up in which kinds of registers, just by
  983. looking at the operands.
  984.  
  985.    The way to refer to the operands in CONDITION is to write
  986. `operands[I]' for operand number I (as matched by `(match_operand I
  987. ...)').  Use the variable `insn' to refer to the last of the insns
  988. being matched; use `prev_nonnote_insn' to find the preceding insns.
  989.  
  990.    When optimizing computations with intermediate results, you can use
  991. CONDITION to match only when the intermediate results are not used
  992. elsewhere.  Use the C expression `dead_or_set_p (INSN, OP)', where INSN
  993. is the insn in which you expect the value to be used for the last time
  994. (from the value of `insn', together with use of `prev_nonnote_insn'),
  995. and OP is the intermediate value (from `operands[I]').
  996.  
  997.    Applying the optimization means replacing the sequence of insns with
  998. one new insn.  The TEMPLATE controls ultimate output of assembler code
  999. for this combined insn.  It works exactly like the template of a
  1000. `define_insn'.  Operand numbers in this template are the same ones used
  1001. in matching the original sequence of insns.
  1002.  
  1003.    The result of a defined peephole optimizer does not need to match
  1004. any of the insn patterns in the machine description; it does not even
  1005. have an opportunity to match them.  The peephole optimizer definition
  1006. itself serves as the insn pattern to control how the insn is output.
  1007.  
  1008.    Defined peephole optimizers are run as assembler code is being
  1009. output, so the insns they produce are never combined or rearranged in
  1010. any way.
  1011.  
  1012.    Here is an example, taken from the 68000 machine description:
  1013.  
  1014.      (define_peephole
  1015.        [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
  1016.         (set (match_operand:DF 0 "register_operand" "=f")
  1017.              (match_operand:DF 1 "register_operand" "ad"))]
  1018.        "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
  1019.        "*
  1020.      {
  1021.        rtx xoperands[2];
  1022.        xoperands[1] = gen_rtx (REG, SImode, REGNO (operands[1]) + 1);
  1023.      #ifdef MOTOROLA
  1024.        output_asm_insn (\"move.l %1,(sp)\", xoperands);
  1025.        output_asm_insn (\"move.l %1,-(sp)\", operands);
  1026.        return \"fmove.d (sp)+,%0\";
  1027.      #else
  1028.        output_asm_insn (\"movel %1,sp@\", xoperands);
  1029.        output_asm_insn (\"movel %1,sp@-\", operands);
  1030.        return \"fmoved sp@+,%0\";
  1031.      #endif
  1032.      }
  1033.      ")
  1034.  
  1035.    The effect of this optimization is to change
  1036.  
  1037.      jbsr _foobar
  1038.      addql #4,sp
  1039.      movel d1,sp@-
  1040.      movel d0,sp@-
  1041.      fmoved sp@+,fp0
  1042.  
  1043. into
  1044.  
  1045.      jbsr _foobar
  1046.      movel d1,sp@
  1047.      movel d0,sp@-
  1048.      fmoved sp@+,fp0
  1049.  
  1050.    INSN-PATTERN-1 and so on look *almost* like the second operand of
  1051. `define_insn'.  There is one important difference: the second operand
  1052. of `define_insn' consists of one or more RTX's enclosed in square
  1053. brackets.  Usually, there is only one: then the same action can be
  1054. written as an element of a `define_peephole'.  But when there are
  1055. multiple actions in a `define_insn', they are implicitly enclosed in a
  1056. `parallel'.  Then you must explicitly write the `parallel', and the
  1057. square brackets within it, in the `define_peephole'.  Thus, if an insn
  1058. pattern looks like this,
  1059.  
  1060.      (define_insn "divmodsi4"
  1061.        [(set (match_operand:SI 0 "general_operand" "=d")
  1062.              (div:SI (match_operand:SI 1 "general_operand" "0")
  1063.                      (match_operand:SI 2 "general_operand" "dmsK")))
  1064.         (set (match_operand:SI 3 "general_operand" "=d")
  1065.              (mod:SI (match_dup 1) (match_dup 2)))]
  1066.        "TARGET_68020"
  1067.        "divsl%.l %2,%3:%0")
  1068.  
  1069. then the way to mention this insn in a peephole is as follows:
  1070.  
  1071.      (define_peephole
  1072.        [...
  1073.         (parallel
  1074.          [(set (match_operand:SI 0 "general_operand" "=d")
  1075.                (div:SI (match_operand:SI 1 "general_operand" "0")
  1076.                        (match_operand:SI 2 "general_operand" "dmsK")))
  1077.           (set (match_operand:SI 3 "general_operand" "=d")
  1078.                (mod:SI (match_dup 1) (match_dup 2)))])
  1079.         ...]
  1080.        ...)
  1081.  
  1082.